package com.klm.easymq.client;

import com.klm.easymq.entity.Message;
import com.klm.easymq.core.IdempotentHandler;
import com.klm.easymq.core.MonitorService;

import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * Easy-MQ 客户端接口
 * 作为 SDK 对外提供的统一调用接口
 * 
 * @author klm
 */
public interface EasyMqClient {
    
    /**
     * 同步发送消息
     * 
     * @param topic 主题
     * @param message 消息内容
     * @return 发送结果
     */
    boolean sendMessage(String topic, Object message);
    
    /**
     * 同步发送消息（带业务键）
     * 
     * @param topic 主题
     * @param message 消息内容
     * @param businessKey 业务键（用于幂等控制）
     * @return 发送结果
     */
    boolean sendMessage(String topic, Object message, String businessKey);
    
    /**
     * 异步发送消息
     * 
     * @param topic 主题
     * @param message 消息内容
     * @return 异步结果
     */
    CompletableFuture<Boolean> sendMessageAsync(String topic, Object message);
    
    /**
     * 异步发送消息（带业务键）
     * 
     * @param topic 主题
     * @param message 消息内容
     * @param businessKey 业务键（用于幂等控制）
     * @return 异步结果
     */
    CompletableFuture<Boolean> sendMessageAsync(String topic, Object message, String businessKey);
    
    /**
     * 批量发送消息
     * 
     * @param topic 主题
     * @param messages 消息列表
     * @return 发送结果
     */
    boolean sendBatchMessages(String topic, List<Object> messages);
    
    /**
     * 根据 traceId 查询消息
     * 
     * @param traceId 消息追踪ID
     * @return 消息对象
     */
    Message getMessageByTraceId(String traceId);
    
    /**
     * 分页查询消息
     * 
     * @param topic 主题（可选）
     * @param status 状态（可选）
     * @param pageNum 页码
     * @param pageSize 页大小
     * @return 消息列表
     */
    List<Message> getMessages(String topic, String status, int pageNum, int pageSize);
    
    /**
     * 获取消息统计信息
     * 
     * @return 统计信息
     */
    Map<String, Object> getMessageStats();
    
    /**
     * 检查消息是否已处理（幂等检查）
     * 
     * @param businessKey 业务键
     * @return 是否已处理
     */
    boolean isMessageProcessed(String businessKey);
    
    /**
     * 标记消息为已处理
     * 
     * @param businessKey 业务键
     * @param expireSeconds 过期时间（秒）
     */
    void markMessageAsProcessed(String businessKey, long expireSeconds);
    
    /**
     * 获取幂等处理器
     * 
     * @return 幂等处理器
     */
    IdempotentHandler getIdempotentHandler();
    
    /**
     * 获取监控服务
     * 
     * @return 监控服务
     */
    MonitorService getMonitorService();
    
    /**
     * 健康检查
     * 
     * @return 健康状态
     */
    boolean isHealthy();
    
    /**
     * 关闭客户端
     */
    void close();
} 